Skip to content

feat(sql): add qn sql clusters (DX-7719) - #63

Open
johnpmitsch wants to merge 3 commits into
mainfrom
dx-7719-add-qn-sql-clusters-to-list-sql-explorer-clusters-in
Open

johnpmitsch wants to merge 3 commits into
mainfrom
dx-7719-add-qn-sql-clusters-to-list-sql-explorer-clusters-in

Conversation

@johnpmitsch

Copy link
Copy Markdown
Collaborator

tl;dr

Adds qn sql clusters (alias ls), which lists the clusters that qn sql query and qn sql schema take as a cluster ID. Updates quicknode-sdk to 0.10.1, the release line that has sql.list_clusters().

Closes DX-7719

Impact

  • New verb: qn sql clusters / qn sql ls. It prints an ID / DISPLAY_NAME table by default and the SDK's JSON array under -o json. It sends the API key and retries like the other read-only commands.
  • qn sql query: the stats line on stderr leaves the credits segment out when the response has no credits value (✓ 2 rows · 0.007s). With credits, the line is the same as before (✓ 2 rows · 135 credits · 0.007s).
  • qn sql --help now ends with an examples block.
  • No existing flag, output shape, or exit code changes.
qn sql clusters
qn sql ls -o json | jq -r '.[].id'
ID                        DISPLAY_NAME
hyperliquid-core-mainnet  Hyperliquid (HyperCore)
solana-mainnet            Solana

Where to focus your review

  • src/commands/sql/mod.rs, stats_line: the only change to existing behavior. SDK 0.10.1 types QueryResponse.credits as Option<i64>.
  • src/commands/sql/mod.rs, clusters and ClustersView: the new verb. It follows schema (keyed client, retrying).
  • Safe to skim: Cargo.lock (one version and checksum), the snapshot file, the tests.

Decisions & tradeoffs

  1. The stats line omits credits when the response has none — a zero or a dash would state a cost the response did not give. To reverse: print a placeholder in stats_line.
  2. qn sql gets a top-level examples block — the working notes ask for one on every top-level noun, and clusters is the first step of the flow. To reverse: remove the after_help attribute on sql::Args.

Technical notes

  • ClustersView wraps Vec<SqlCluster>, so the serialized formats match the SDK's shape: a bare array of { id, display_name }.
  • CLAUDE.md now names quicknode-sdk 0.10 as the wrapped version.

How I verified it

AI: built, tested, and self-reviewed (jreview) by john-pipeline running Claude Code.

Ran:

  • cargo fmt --check passes
  • cargo clippy --all-targets -- -D warnings passes
  • cargo test passes (549 tests; 6 new: 2 unit tests for the stats line, 3 integration tests in tests/sql.rs, 1 table snapshot)
  • cargo build --release passes with no warnings from this crate
  • The built binary against a local mock server: sql clusters -o json, sql ls -o table, sql ls -o md print the two clusters and exit 0; a 401 prints the unauthorized message and exits 2
  • Reviewer: run qn sql clusters against the live API with a key

Not checked:

  • qn sql clusters against the live API.

Confidence assessment: how likely is this to affect or break prod

Overall: low risk of breakage, small blast radius if it does, fully reversible by code revert.

Concern Likelihood Why Containment
Existing commands after the SDK update Very low 0.9.0 to 0.10.1 changes only the SQL client in the SDK; the 543 existing tests pass unchanged Revert the dependency commit
qn sql query stats line Low Unit tests cover the line with and without credits; an integration test covers a response without credits Revert; stats go to stderr only, stdout is not affected
Response shape of the clusters endpoint Low The SDK type matches the documented { id, display_name } shape; extra fields are ignored A mismatch surfaces as a decode error, not wrong output

Not verifiable from here:

  • Whether the live endpoint returns statuses other than 200 and 401 in normal use.

SDK 0.10.1 makes the credits value of a SQL query response optional.
The stats line of qn sql query now leaves the credits segment out when
the response has none, and prints it as before when it is there.

Tests: 2 unit tests for the stats line, 1 integration test for a query
response without credits.
qn sql clusters (alias ls) lists the clusters that qn sql query and
qn sql schema take as a cluster id. It prints an ID / DISPLAY_NAME table
by default and the SDK's JSON under -o json. It sends the API key and
retries like the other read-only commands.

The README and the qn agent context guide list the new command.

Tests: 2 integration tests (happy path with the ls alias and the API key
header, 401 to exit 2) and 1 table snapshot.
The notes named the SDK minor version the CLI wraps. It is 0.10 after
the dependency update.
@johnpmitsch
johnpmitsch marked this pull request as ready for review November 16, 2026 05:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant